\n This library lets you use customisable branch-and-bound search. It\n is primarily intended for use with the colgen library in implementing\n branch-and-price algorithms, but can be used with arbitrary\n user-defined node solution, separation and selection goals.\n When application specific methods are not required for node\n separation and/or selection the use of built-in depth-first\n and best-first node selection, and branching on most fractional\n variable or generalised upper bound constraint may be specified.\n When the relaxed problem to be solved at a node involves an eplex\n instance branching may additionally be specified by built-in\n objective coefficient, estimate- or lower-bounding based methods,\n and best-estimate node selection may be used.\n
\n")). :- comment(bfs_branch / 1, [template : "BfsInstance:bfs_branch(+Branch)", args : ["Branch" : "Prolog term"], summary : "Post a branching constraint to the bfs instance BfsInstance.", see_also : [solver_setup / 2, solver_setup / 3, get / 2], desc : html("\n Post a new branching constraint Branch to the bfs instance\n BfsInstance. The constraint will be used to create a new child node\n of the current open node in the search tree for BfsInstance.\n Branch may be any prolog term, but clearly should be an\n appropriate constraint for the node relaxation solver associated with\n BfsInstance. \n
")]). :- comment(bfs_instance / 1, [amode : bfs_instance(++), args : ["BfsInstance" : "Bfs instance name (atom)"], summary : "Initialises the bfs instance BfsInstance.", desc : html("\n Initialises the bfs instance BfsInstance. A bfs instance is an\n instance of the best first search solver, with which node\n relaxation and separation solvers can be associated and used to\n optimise the problem constraints posted to the relaxed node solver\n with respect to its objective using a specified node ordering scheme.\n In particular best-first and best-estimate search schemes are\n supported and application-specific schemes may be easily defined by\n the user.\n
\n If BfsInstance is not an already existing bfs instance, a new bfs\n instance will be created and initialised. If it is an existing bfs\n instance, and it is not currently being used (having no associated\n solvers), it is effectively reinitialised. Otherwise, the predicate\n aborts with an error. Note that a bfs instance is a module, and each\n bfs instance can be associated with at most one relaxation and one\n separation solver at any time and vice versa.\n
\n "), see_also : [integers / 1, bfs_branch / 1, node_info / 5, solver_setup / 2, solver_setup / 3, solve / 1, get / 2, var_get / 3, bfs : statistics / 0]]). :- comment(get / 2, [template : "BfsInstance:get(++What, -Value)", args : ["What" : "Specification for information wanted (atom)", "Value" : "Returned value of What"], summary : "Obtain information for the problem associated with BfsInstance.", exceptions : [6 : "What is not a valid value."], desc : html("\n Retrieve information about the problem associated with the bfs\n instance BfsInstance. What can take one of the following values:\n\n
\n\n
\n The variable or list of variables Ints will be considered integers\n when solving the problem associated with BfsInstance. Note that\n this does not mean that they will be treated as integers by the\n specified node relaxation solver, rather that they will be considered\n as candidates for branching decisions in nodes where their solution\n value is not integral (to within a tolerance parameter set in the\n options list of BfsInstance:solver_setup/3). The predefined\n node separation schemes will branch on these variables. User-defined\n node separation predicates may access the fractional variables\n at the current node via a call to BfsInstance:get/2"), see_also : [solver_setup / 3, get / 2]]). :- comment(node_cost / 1, [template : "BfsInstance:node_cost(+Val)", args : ["Val" : "Solution cost for problem (number)"], summary : "Set solution cost for the problem at a node.", desc : html("
\n Set the solution cost for the problem at the current open node of\n the search tree associated with the bfs instance BfsInstance.\n
")]). :- comment(node_info / 5, [template : "BfsInstance:node_info(+Var, ?Lo, ?Hi, ?Val, ?RC)", args : ["Var" : "A solver problem variable for solver the associated with BfsInstance", "Lo" : "Lower bound for Var (number)", "Hi" : "Upper bound for Var (number)", "Val" : "Solution value for Var (number)", "RC" : "Reduced cost for Var (number)"], summary : "Get or set node bounds and solution information for an individual solver problem variable Var.", desc : html("\n Retrieve or update bounds and solution information for an\n individual solver problem variable Var for the current open node of\n the search tree associated with the bfs instance BfsInstance. If Var\n was not already a problem variable for BfsInstance it will now be\n considered one. If reduced costs are available in problems\n involving eplex instances supplying these to the bfs solver can lead\n to improved pruning.\n
")]). :- comment(solve / 1, [template : "BfsInstance:solve(-Cost)", args : ["Cost" : "The optimal solution cost of the problem associated with BfsInstance"], summary : "Optimise the problem associated with BfsInstance.", fail_if : "No solution exists satisfying the global feasibility conditions.", see_also : [solver_setup / 2, solver_setup / 3, get / 2, var_get / 3, bfs : statistics / 0], desc : html("\n A solver setup with solver_setup/2 or solver_setup/3 is triggered\n using this predicate.\n
\n The node relaxation and separation solvers are applied to the next\n selected node of the problem represented by Handle repeatedly until\n no more open nodes remain. The criteria for node selection order\n depends on the options given to solver_setup/2,3. solve/1 fails if\n there is no solution or succeeds if an optimal solution is found,\n returning the solution's cost in Cost. After a success, various\n solution information and statistics can be retrieved using get/2,\n var_get/3 and statistics/0.\n
")]). :- comment(solver_setup / 2, [template : "BfsInstance:solver_setup(+OptSense, +Solver)", args : ["OptSense" : "Optimisation direction: min or max", "Solver" : "Node relaxation solver"], summary : "Setup a bfs solver tree for bfs instance BfsInstance.", see_also : [integers / 1, bfs_branch / 1, node_info / 5, solver_setup / 3, solve / 1, get / 2, var_get / 3, bfs : statistics / 0], desc : html("\n Setup a new solver tree for the bfs instance BfsInstance. The tree\n will be associated with BfsInstance; BfsInstance must not already\n have a solver tree associated with it. Once the solver tree is setup,\n it can be optimised via solve/1.\n
\n This is a simplified version of solver_setup/3, it is equivalent to\n calling solver_setup/3 with the following default options:\n
\n solver_setup(OptSense, Solver, [])\n\n")]). :- comment(solver_setup / 3, [template : "BfsInstance:solver_setup(+OptSense, +Solver, ++ListOfOptions)", args : ["OptSense" : "Optimisation direction: min or max", "Solver" : "Node relaxation solver", "ListOfOptions" : "List of solver options"], summary : "Setup a bfs solver tree for bfs instance BfsInstance.", see_also : [integers / 1, bfs_branch / 1, node_info / 5, solver_setup / 2, solve / 1, get / 2, var_get / 3, bfs : statistics / 0], desc : html("
\n Setup a new solver tree for the bfs instance BfsInstance. The tree\n will be associated with BfsInstance; BfsInstance must not already\n have a solver tree associated with it. Once the solver tree is setup,\n it can be optimised via solve/1. This predicate allow various\n options to be specified when setting up the solver state via\n ListOfOptions.\n
\n OptSense is the optimisation direction. Note that this\n is assumed to be the same as the sense of optimisation used in\n Solver. It is the user's responsibility to ensure \n that this is in fact the case. OptSense is used internally\n for bound updates and pruning, and for node ordering with the built-in\n best-first and best-estimate node selection methods.\n
\n Solver is the node relaxed problem solver. It is either a\n user-defined predicate or an eplex instance or handle, for which a\n built-in node relaxation solver is available.\n\n
\nListOfOptions are:\n\n
\n
\n
\n
\n
\n
When using estimate-based dichotomic node separation methods\n with a problem involving an eplex instance up and down pseudo-costs\n are assigned to each variable and generalised upper bound constraint \n branch-point representing the estimated degradation in objective\n cost per unit change in variable or constraint value incurred on\n that branch.\n
PCInit specifies the method used to initialise these\n values when a variable or constraint branch-point is first considered\n for branching:\n
PCUpdate is an atom specifying the method used to\n update these values throughout the search tree once the variable\n or constraint has been branched on:\n
PCRatio is a float between 0 and 1 and is used in\n calculating the number of external solver iterations to perform\n when explicitly calculating initial pseudo-cost estimates; the\n default value is 0.05. Setting small ratios will result in faster\n node separation, but the initial estimates for variables and\n constraints on which the branching decisions are taken will be less\n accurate. Setting larger values will result in more work being performed\n in node separation and better estimates for the branching\n decisions. The optimum value will be problem specific, although in \n general the overhead of performing a total number of iterations\n more than a small ratio of the root node iterations will outweigh the\n benefit obtained.\n\n
\n
\n
\n
\n Display statistics for the search tree associated with the bfs\n instance BfsInstance: total number of nodes created, total search\n time, number of nodes solved, node solution time, number of nodes\n separated, node separation time, total number of global feasible\n solutions found, first and optimal global solution solution time.\n
\n")]). :- comment(var_get / 3, [template : "BfsInstance:var_get(+Var, ++What, -Value)", args : ["Var" : "A solver problem variable for the solver associated with BfsInstance", "What" : "Specification for information wanted (atom)", "Value" : "Returned value of What"], summary : "Obtain information for an individual solver problem variable Var.", exceptions : [6 : "What is not a valid value."], desc : html("\n Retrieve information about solver results related to a particular\n variable, for the bfs instance BfsInstance. Fails if Var is not a\n problem variable for BfsInstance. What can take one of the following\n values: \n\n
\n\n
\n\n